\section{List.mui}

MUI's list class is very powerful. It handles all types
of entries, from a simple string to a complicated structure
with many associated resources. Multi column lists are
also supported, the format for a column is adjustable.

Lists support any kind of sorting, multi selection and
an active entry that can be controlled with the mouse
or the cursor keys.

Note: A list object alone doesn't make much sense, you
should always use it as child of a listview object.
This one attaches a scrollbar and handles all user
input.

\subsection[MUIM\_List\_Clear]{MUIM\_List\_Clear (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Clear,);

\subsubsection*{FUNCTION}
Clear the list, all entries are removed. If a destruct
hook is set it will be called for every entry.

\subsubsection*{SEE ALSO}
MUIM\_List\_Insert, MUIA\_List\_DestructHook

\subsection[MUIM\_List\_Exchange]{MUIM\_List\_Exchange (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Exchange,LONG pos1, LONG pos2);

\subsubsection*{FUNCTION}
Exchange two entries in a list.

\subsubsection*{INPUTS}
\begin{description}
\item[pos1] - number of the first entry.
\item[pos2] - number of the second entry.
\end{description}

Possible special values since muimaster.library V9:

\begin{center} \begin{tabular}{lrl}
MUIV\_List\_Exchange\_Top    &   0&\\
MUIV\_List\_Exchange\_Active  & -1&\\
MUIV\_List\_Exchange\_Bottom &  -2&\\
MUIV\_List\_Exchange\_Next   &  -3& /$\ast$ only valid for second parameter $\ast$/\\
MUIV\_List\_Exchange\_Previous& -4& /$\ast$ only valid for second parameter $\ast$/ \\
\end{tabular} \end{center}
 
\subsubsection*{SEE ALSO}
MUIM\_List\_Insert, MUIM\_List\_Remove, MUIM\_List\_Move

\subsection[MUIM\_List\_GetEntry]{MUIM\_List\_GetEntry (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_GetEntry,LONG pos, APTR $\ast$entry);

\subsubsection*{FUNCTION}
Get an entry of a list.

\subsubsection*{INPUTS}
\begin{description}
\item[pos]   - Number of entry, MUIV\_List\_GetEntry\_Active can
be used to get the active entry.

\item[entry] - Pointer to a longword where the entry will
be stored. If the entry is not available
(either because you are out of bounds or
because there is no active entry), you will
receive a NULL.
\end{description}
   
\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* iterate through a list containing file info blocks */

for (i=0;;i++)
{
    struct FileInfoBlock *fib;

    DoMethod(list,MUIM_List_GetEntry,i,&fib);
    if (!fib) break;

    printf("%s\n",fib->fib_FileName);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_List\_Insert, MUIM\_List\_Remove

\subsection[MUIM\_List\_Insert]{MUIM\_List\_Insert (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Insert,APTR $\ast$entries, LONG count, LONG pos);

\subsubsection*{FUNCTION}
Insert new entries into a list.
When the list has a construct hook, the given pointers
won't be inserted directly but instead passed through
to the construct hook.

\subsubsection*{INPUTS}
\begin{description}
\item[entries] - pointer to an array of pointers to be inserted.
Warning: This is a pointer to a pointer. See
example for details.

\item[count]   - Number of elements to be inserted. If count==-1,
entries will be inserted until NULL pointer in
the entries array is found.

\item[pos]     - New entries will be added in front of this entry.
\begin{center} \begin{tabular}{ll}
MUIV\_List\_Insert\_Top: &insert as first entry.\\
MUIV\_List\_Insert\_Active:& insert in front of the active entry.\\
MUIV\_List\_Insert\_Sorted:& insert sorted.\\
MUIV\_List\_Insert\_Bottom:& insert as last entry.\\
\end{tabular} \end{center}
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* insert a string */
char *str = "New entry";
DoMethod(list,MUIM_List_Insert,&str,1,MUIV_List_Insert_Bottom);

/* insert an array */
char *str[] =
{
   "Entry 1",
   "Entry 2",
   "Entry 3",
   "Entry 4",
   NULL
};
DoMethod(list,MUIM_List_Insert,str,-1,MUIV_List_Insert_Bottom);

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_List\_Remove, MUIA\_List\_ConstructHook

\subsection[MUIM\_List\_InsertSingle]{MUIM\_List\_InsertSingle (V7)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_InsertSingle,APTR entry, LONG pos);

\subsubsection*{FUNCTION}
Insert one new entry into a list. Using MUIM\_List\_Insert has
caused some confusion since it takes an array to items instead
a single item. To insert single items, MUIM\_List\_InsertSingle
is the better choice.

When the list has a construct hook, the given pointer
won't be inserted directly but instead passed through
to the construct hook.

\subsubsection*{INPUTS}
\begin{description}
\item[entry]   - item to insert.

\item[pos]     - New entry will be added in front of this entry.
\begin{center} \begin{tabular}{ll}
MUIV\_List\_Insert\_Top: &insert as first entry.\\
MUIV\_List\_Insert\_Active:& insert in front of the active entry.\\
MUIV\_List\_Insert\_Sorted:& insert sorted.\\
MUIV\_List\_Insert\_Bottom:& insert as last entry.\\
\end{tabular} \end{center}
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* insert a string */
DoMethod(list,MUIM_List_InsertSingle,"foobar",MUIV_List_Insert_Bottom);

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_List\_Remove, MUIA\_List\_ConstructHook, MUIM\_List\_InsertSingle

\subsection[MUIM\_List\_Jump]{MUIM\_List\_Jump (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Jump,LONG pos);

\subsubsection*{FUNCTION}
Scroll any entry into the visible part of a list.

\subsubsection*{NOTE}
Jumping to an entry doesn't mean to make this
entry the active one. This can be done by
setting the MUIA\_List\_Active attribute.

\subsubsection*{INPUTS}
\begin{description}
\item[pos] - Number of the entry that should be made visible. Use \linebreak
MUIV\_List\_Jump\_Active to jump to the active entry.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* line 42 is interesting, so make it visible */
DoMethod(list,MUIM_List_Jump,42);

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_Active

\subsection[MUIM\_List\_Move]{MUIM\_List\_Move (V9)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Move,LONG from, LONG to);

\subsubsection*{FUNCTION}
Move an entry from one position to another.

\subsubsection*{INPUTS}
\begin{description}
\item[pos1] - number of the first entry.
\item[pos2] - number of the second entry.
\end{description}
   
Possible special values since muimaster.library V9:

\begin{center} \begin{tabular}{lrl}
MUIV\_List\_Move\_Top     &  0&\\
MUIV\_List\_Move\_Active  & -1&\\
MUIV\_List\_Move\_Bottom  & -2&\\
MUIV\_List\_Move\_Next    & -3& /$\ast$ only valid for second parameter $\ast$/\\
MUIV\_List\_Move\_Previous& -4& /$\ast$ only valid for second parameter $\ast$/\\
\end{tabular} \end{center}

\subsubsection*{SEE ALSO}
MUIM\_List\_Insert, MUIM\_List\_Remove, MUIM\_List\_Exchange

\subsection[MUIM\_List\_NextSelected]{MUIM\_List\_NextSelected (V6)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_NextSelected,LONG $\ast$pos);

\subsubsection*{FUNCTION}
Iterate through the selected entries of a list.
This method steps through the contents of a (multi
select) list and returns every entry that is currently
selected. When no entry is selected but an entry is
active, only the active entry will be returned.

This behaviour will result in not returning the
active entry when you have some other selected
entries somewhere in your list. Since the active
entry just acts as some kind of cursor mark,
this seems to be the only sensible possibility
to handle multi selection together with keyboard
control.

\subsubsection*{INPUTS}
\begin{description}
\item[pos] - a pointer to longword that will hold the number
of the returned entry. Must be set to
MUIV\_List\_NextSelected\_Start at start of iteration.
Is set to MUIV\_List\_NextSelected\_End when iteration
is finished.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

/* Iterate through a list with FileInfoBlocks */

struct FileInfoBlock *fib;
LONG id = MUIV_List_NextSelected_Start;

for (;;)
{
   DoMethod(list,MUIM_List_NextSelected,&id);
   if (id==MUIV_List_NextSelected_End) break;

   DoMethod(list,MUIM_List_GetEntry,id,&fib);
   printf("selected: %s\n",fib->fib_FileName);
}


\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_List\_Select

\subsection[MUIM\_List\_Redraw]{MUIM\_List\_Redraw (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Redraw,LONG pos);

\subsubsection*{FUNCTION}
If you made some changes to an entry of your list and
want these changes to be shown in the display, you will
have to call this method.

\subsubsection*{INPUTS}
\begin{description}
\item[pos] - Number of the line to redraw. When the line is not
currently visible, nothing will happen. Specials:
\begin{center} \begin{tabular}{ll}
MUIV\_List\_Redraw\_Active:& redraw the active line (if any),\\
MUIV\_List\_Redraw\_All:& redraw all lines.\\
\end{tabular} \end{center}
\end{description}
   
\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* do a complete refresh: */
DoMethod(list,MUIM_List_Redraw,MUIV_List_Redraw_All);

\end{verbatim}
\normalsize
\subsection[MUIM\_List\_Remove]{MUIM\_List\_Remove (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Remove,LONG pos);

\subsubsection*{FUNCTION}
Remove an entry from a list.

\subsubsection*{INPUTS}
\begin{description}
\item[pos] - number of the entry to be removed or one of\\
MUIV\_List\_Remove\_First,\\
MUIV\_List\_Remove\_Active,\\
MUIV\_List\_Remove\_Last.\\
When the active entry is removed, the following entry
will become active.
\end{description}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* when delete is pressed, remove the active entry */
DoMethod(btdel,MUIM_Notify,MUIA_Pressed,FALSE,
   list,2,MUIM_List_Remove,MUIV_List_Remove_Active);

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_List\_Insert, MUIA\_List\_DestructHook

\subsection[MUIM\_List\_Select]{MUIM\_List\_Select (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Select,LONG pos, LONG seltype, LONG $\ast$state);

\subsubsection*{FUNCTION}
Select/deselect a list entry or ask an entry if its
selected.

\subsubsection*{INPUTS}
\begin{description}
\item[pos]     - Number of the entry or
\begin{center} \begin{tabular}{ll}
MUIV\_List\_Select\_Active & for the active entry.\\
MUIV\_List\_Select\_All    & for all entries.\\
\end{tabular} \end{center}

\item[seltype] - Value:
\begin{center} \begin{tabular}{ll}
MUIV\_List\_Select\_Off &    unselect entry.\\
MUIV\_List\_Select\_On      &select entry.\\
MUIV\_List\_Select\_Toggle &  toggle entry.\\
MUIV\_List\_Select\_Ask    & just ask about the state.\\
\end{tabular} \end{center}

\item[state]   - Pointer to a longword. If not NULL, this will
be filled with the current selection state.
\end{description}

\subsubsection*{NOTE}
Since version V9 of muimaster.library:
If pos==MUIV\_List\_Select\_All and seltype==MUIV\_List\_Select\_Ask,
state will be filled with the total number of selected entries.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* toggle selection state of active entry */
DoMethod(list,MUIM_List_Select,MUIV_List_Select_Active,
   MUIV_List_Select_Toggle,NULL);

/* select all entries */
DoMethod(list,MUIM_List_Select,MUIV_List_Select_All,
   MUIV_List_Select_On,NULL);

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_MultiTest\_Hook

\subsection[MUIM\_List\_Sort]{MUIM\_List\_Sort (V4)}

\subsubsection*{SYNOPSIS}
DoMethod(obj,MUIM\_List\_Sort,);

\subsubsection*{FUNCTION}
Sort the list. MUI uses an iterative quicksort algorithm,
no stack problems will occur.

\subsubsection*{SEE ALSO}
MUIA\_List\_CompareHook

\subsection[MUIA\_List\_Active]{MUIA\_List\_Active -- (V4) [ISG], LONG}

\subsubsection*{SPECIAL INPUTS}
MUIV\_List\_Active\_Off\\
MUIV\_List\_Active\_Top\\
MUIV\_List\_Active\_Bottom\\
MUIV\_List\_Active\_Up\\
MUIV\_List\_Active\_Down\\
MUIV\_List\_Active\_PageUp\\
MUIV\_List\_Active\_PageDown

\subsubsection*{FUNCTION}
Reading this attribute will return the number of
the active entry (the one with the cursor on it).
The result is between 0 and MUIA\_List\_Entries-1
or MUIV\_List\_Active\_Off, in which case there is
currently no active entry.

Setting the attribute will cause the list to
move the cursor to the new position and scroll
this position into the visible area.

\subsubsection*{SEE ALSO}
MUIA\_List\_Entries, MUIA\_List\_First, MUIA\_List\_Visible

\subsection[MUIA\_List\_AdjustHeight]{MUIA\_List\_AdjustHeight -- (V4) [I..], BOOL}

\subsubsection*{FUNCTION}
A list with MUIA\_List\_AdjustHeight set to true is exactly
as high as all of its entries and not resizable. This is
only possible when the list is filled $\ast$before$\ast$ the window
is opened.

\subsubsection*{SEE ALSO}
MUIA\_List\_AdjustWidth

\subsection[MUIA\_List\_AdjustWidth]{MUIA\_List\_AdjustWidth -- (V4) [I..], BOOL}

\subsubsection*{FUNCTION}
A list with MUIA\_List\_AdjustWidth set to true is exactly
as wide as the widest entry and not resizable. This is
only possible when the list is filled {\bf before} the window
is opened.

\subsubsection*{SEE ALSO}
MUIA\_List\_AdjustHeight

\subsection[MUIA\_List\_CompareHook]{MUIA\_List\_CompareHook -- (V4) [IS.], struct Hook $\ast$}

\subsubsection*{FUNCTION}
If you plan to have the entries of your list sorted
(either by inserting them sorted or by using the
MUIM\_List\_Sort method) and if the entries of your
list are not simple strings, you {\bf must} supply
a compare hook.

This hook will be called with one list element in A1
and another one in A2. You should return

\begin{center} \begin{tabular}{c|lcl}
return value & \multicolumn{3}{c}{statement}\\ \hline
-1 &  e1& \flq & e2\\
0 &  e1& ==& e2\\
1 &  e1& \frq & e2\\
\end{tabular} \end{center}

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* the builtin string compare function */

        LONG __asm cmpfunc(_a1 char *s1,_a2 char *s2)
{
   return(stricmp(s1,s2));
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_ConstructHook, MUIA\_List\_DestructHook

\subsection[MUIA\_List\_ConstructHook]{MUIA\_List\_ConstructHook -- (V4) [IS.], struct Hook $\ast$}

\subsubsection*{SPECIAL INPUTS}
MUIV\_List\_ConstructHook\_String

\subsubsection*{FUNCTION}
The construct hook is called whenever you add an
entry to your list. MUI will not insert the given
pointer directly, but instead call the construct
hook and add its result code.

Imagine you want to display a list of entries
in a directory. You could step through it
using Examine()/ExNext() and directly use the
MUIM\_List\_Insert method on your file info block
buffer.

Your construct hook will be called with this
file info block as parameter, makes a copy of
it and returns the address of that copy. Thats
what is actually added to the list.

The corresponding destruct hook is called whenever
an entry shall be removed. It's task would simply be
to free the memory and maybe other resources concering
this entry that were allocated by the construct hook.

Using these two functions, you will never have to
worry about freeing the memory used by your list
entries. Clearing the list or disposing the list
object will automatically remove all entries and
thus free the associated resources.

The construct hook will be called with the hook
in A0, the data given to \linebreak MUIM\_List\_Insert as message
in register A1 and with pointer to a standard kick 3.x
memory pool in A2. If you want, you can use the exec
or amiga.lib functions for allocating memory within
this pool, but this is only an option.

If the construct hook returns NULL, nothing will be
added to the list.

There is a builtin construct hook available called \linebreak
MUIV\_List\_ConstructHook\_String. This expects that
you only add strings to your list and will make
a local copy of this string to allow you destroying
the original. Of course you {\bf must} also use
MUIV\_List\_DestructHook\_String in this case.

Without construct and destruct hooks, you are responsible
for allocating and freeing entries yourself.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* the builtin string construct and destruct functions: */

APTR __asm consfunc(_a2 APTR pool,_a1 char *str)
{
   char *new;
   if (new=AllocPooled(pool,strlen(str)+1))
      strcpy(new,str);
   return(new);
}

VOID __asm desfunc(_a2 APTR pool,_a1 char *entry)
{
   FreePooled(pool,entry,strlen(entry)+1);
}

/* for more sophisticated hooks see demo program WbMan.c */

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_DestructHook, MUIA\_List\_DisplayHook

\subsection[MUIA\_List\_DestructHook]{MUIA\_List\_DestructHook -- (V4) [IS.], struct Hook $\ast$}

SPECIAL INPUTS
MUIV\_List\_DestructHook\_String

\subsubsection*{FUNCTION}
Set up a destruct hook for your list. For detailed
explanation see MUIA\_List\_ConstructHook.

\subsubsection*{SEE ALSO}
MUIA\_List\_ConstructHook, MUIA\_List\_DisplayHook

\subsection[MUIA\_List\_DisplayHook]{MUIA\_List\_DisplayHook -- (V4) [IS.], struct Hook $\ast$}

\subsubsection*{FUNCTION}
Since MUI's lists can handle any kind of entries,
you have to supply a display hook to specify what
should actually be shown in the display.

The hook will be called with a pointer to the
entry to be displayed in A1 and a pointer to
a string array containing as many entries as
your list may have columns in A2.

You must fill this array with the strings that
you want to display.

Note: You can of course use MUI's text engine
facilities here to create e.g. right aligned
or centered columns.

Without a display hook, MUI expects a simple one
columned string list.

See MUIA\_List\_Format for details about column handling.

\subsubsection*{NOTE}
Since version 6 of MUI, the display hook also gets the
position of the current entry as additional parameter. You
can easily do e.g. some line numbering using this feature. The
number (from 0 to NumEntries-1) is stored in the longword
{\bf preceding} the column array (see example below).

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* list of file info blocks, two columned, name and size */

LONG __asm dispfunc(_a2 char **array,_a1 struct FileInfoBlock *fib)
{
   static char buf1[20],buf2[20];

   if (fib->fib_EntryType<0)
     sprintf(buf2,"\33r%ld",fib->fib_Size);
   else
     strcpy(buf2,"\33r(dir)");

   sprintf(buf1,"%ld",array[-1]);   // get the line number.

   *array++ = buf1;
   *array++ = fib->fib_FileName;
   *array   = buf2;

   return(0);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_Format, MUIA\_Text\_Contents

\subsection[MUIA\_List\_Entries]{MUIA\_List\_Entries -- (V4) [..G], LONG}

\subsubsection*{FUNCTION}
Get the current number of entries in the list.

\subsubsection*{SEE ALSO}
MUIA\_List\_First, MUIA\_List\_Visible, MUIA\_List\_Active

\subsection[MUIA\_List\_First]{MUIA\_List\_First -- (V4) [..G], LONG}

\subsubsection*{FUNCTION}
Get the number of the entry displayed on top of
the list. You have to be prepared to get a result
of -1, which means that the list is not visible
at all (e.g. when the window is iconifed).

\subsubsection*{SEE ALSO}
MUIA\_List\_Visible, MUIA\_List\_Entries, MUIA\_List\_Active

\subsection[MUIA\_List\_Format]{MUIA\_List\_Format -- (V4) [ISG], STRPTR}

\subsubsection*{FUNCTION}
MUI has the ability to handle multi column lists. To define
how many columns should be displayed and how they should be
formatted, you specify a format string.

This format string must contain one entry for each column
you want to see. Entries are seperated by commas, one
entry is parsed via dos.library/ReadArgs().

The template for a single entry looks like this:

DELTA=D/N, PREPARSE=P/K, WEIGHT=W/N,
MINWIDTH=MIW/N, MAXWIDTH=MAW/N, COL=C/N

\begin{description}
\item[DELTA]
Space in pixel between this column and the next.
the last displayed column ignores this setting.
Defaults to 4.

\item[PREPARSE]
A preparse value for this column. Setting this
e.g. to ''$\backslash$33c'' would make the column centered.
See MUIA\_Text\_Contents for other control codes.

\item[WEIGHT]
The weight of the column. As with MUI's group
class, columns are layouted with a minimum
size, a maximum size and weight. A column with
a weight of 200 would gain twice the space than
a column with a weight of 100.
Defaults to 100.

\item[MINWIDTH]
Minimum percentage width for the current column.
If your list is 200 pixel wide and you set this
to 25, your column will at least be 50 pixel.
The special value -1 for this parameter means that
the minimum width is as wide as the widest entry in
this column. This ensures that every entry will be
completely visible (as long as the list is wide enough).
Defaults to -1.

\item[MAXWIDTH]
Maximum percentage width for the current column.
If your list is 200 pixel wide and you set this
to 25, your column will not be wider as 50 pixel.
The special value -1 for this parameter means that
the maximum width is as wide as the widest entry in
this column.
Defaults to -1.

\item[COL]
This value adjusts the number of the current column.
This allows you to adjust the order of your columns
without having to change your display hook. See
example for details.
Defaults to current entry number (0,1,...)
\end{description}

If your list object gets so small there is not enough
place for the minwidth of a column, this column will
be hidden completely and the remaining space is
distributed between the remaining columns. This is not
true if the column is the first column, in this case
the entries will simply be clipped.

\subsubsection*{NOTE}
 You will have as many columns in your list as
entries in the format string (i.e. number of
commas + 1). Empty entries, e.g. with a format
string of '',,,,'' are perfectly ok.

The default list format is an empty string (''''), this
means a one column list without special formatting.

\subsubsection*{BUGS}
Currently there is a maximum of 64 columns for a list.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* Three column list without further formatting: */
MUIA_List_Format: ",,"

/* Three column list, middle column centered: */
MUIA_List_Format: ",P=\33c,"

/* Three column list, display order 2 1 0: */
MUIA_List_Format: "COL=2,COL=1,COL=0"

/* now something more complex.           */
/* the display hook defines six entries: */
dispfunc(_a2 char **array,_a1 struct Article *at)
{
   *array++ = at->FromName; // col 0
   *array++ = at->FromPath; // col 1
   *array++ = at->ToName;   // col 2
   *array++ = at->ToPath;   // col 3
   *array++ = at->Date;     // col 4
   *array   = at->Subject;  // col 5
}

/* but we only want to have fromname, date and subject
/* actually displayed, subject shoud be centered: */
MUIA_List_Format, "COL=0,COL=4,COL=5 P=\33c"

/* maybe this looks kind of silly, why not make our  */
/* display hook only fill in these three columns.    */
/* well, if you would e.g. make the format string    */
/* user configurable and document what your display  */
/* hook puts into the array, the user could decide   */
/* what columns he actually wants to see.            */
/* The supplied example DFView does something like   */
/* that.                                             */

/* two column list:   ! Eye    1234 !
                              ! Foot     22 !
                              ! Nose  22331 ! */

MUIA_List_Format, "MAW=100,P=\33r"

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_DisplayHook, MUIA\_Text\_Contents

\subsection[MUIA\_List\_InsertPosition]{MUIA\_List\_InsertPosition -- (V9) [..G], LONG}

\subsubsection*{FUNCTION}
After insertion of an element with MUIM\_List\_Insert,
you can query the position of the new entry by
getting this attribute.

\subsection[MUIA\_List\_MultiTestHook]{MUIA\_List\_MultiTestHook -- (V4) [IS.], struct Hook $\ast$}

\subsubsection*{FUNCTION}
If you plan to have a multi selecting list but not
all of your entries are actually multi selectable
(e.g. in a file requester), you can supply a
MUIA\_List\_MultiTestHook.

It will be called with a pointer to an entry in
A1 and should return TRUE if the entry is multi
selectable, FALSE otherwise.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
/* multi test func for a list of file info blocks */

LONG __asm mtfunc(_a1 struct FileInfoBlock *fib)
{
   if (fib->fib_DirEntryType<0)
      return(TRUE);
   else
      return(FALSE);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_ConstructHook, MUIA\_List\_DestructHook

\subsection[MUIA\_List\_Quiet]{MUIA\_List\_Quiet -- (V4) [.S.], BOOL}

\subsubsection*{FUNCTION}
If you add/remove lots of entries to/from a currently visible
list, this will cause lots of screen action and slow down
the operation. Setting MUIA\_List\_Quiet to true will
temporarily prevent the list from being refreshed, this
refresh will take place only once when you set it back
to false again.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
set(list,MUIA_List_Quiet,TRUE);
AddThousandEntries(list);
set(list,MUIA_List_Quiet,FALSE);

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIM\_List\_Insert, MUIM\_List\_Remove

\subsection[MUIA\_List\_SourceArray]{MUIA\_List\_SourceArray -- (V4) [I..], APTR}

\subsubsection*{FUNCTION}
The NULL terminated array given here is immediately inserted into the
list after object creation time.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
static const char *KeyList[] =
{
   "Cursor Up",
   "Cursor Down",
   "Cursor Left",
   "Cursor Right",
   NULL;
};

LV_Keys = ListviewObject,
   MUIA_Listview_List, ListObject,
      InputListFrame,
      MUIA_List_AdjustWidth, TRUE,
      MUIA_List_SourceArray, KeyList,
      End,
   End;

\end{verbatim}
\normalsize
\subsection[MUIA\_List\_Title]{MUIA\_List\_Title -- (V6) [ISG], char $\ast$}

\subsubsection*{FUNCTION}
Specify a title for the current list. The title is displayed
at the very first line and doesn't scroll away when the list
top position moves.

Usually, the title is just a string. However, if you have
a multi column list with a custom display hook and you
want to have seperate titles for each of your columns,
you can set this attribute to TRUE. In this case, whenever
MUI feels that the list title has to be drawn, it will
call your display hook with a NULL entry pointer. Your
hook has to check for this NULL entry and fill the
given string array with your column titles. Layout of
the column titles follows the same rules as layout
of the lists entries.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

/* display function for a multi columned file list with titles */

LONG __asm DisplayFunc(_a2 char **array,_a1 struct Entry *e)
{
   struct Data *data = hook->h_Data;

   if (e)
   {
      *array++ = e->Name;
      *array++ = e->Size;
      *array++ = e->Date;
      *array++ = e->Time;
      *array++ = e->Flags;
      *array   = e->Comment;
   }
   else
   {
      *array++ = "Name";
      *array++ = "Size";
      *array++ = "Date";
      *array++ = "Time";
      *array++ = "Flags";
      *array   = "Comment";
   }

   return(0);
}

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_List\_DisplayHook

\subsection[MUIA\_List\_Visible]{MUIA\_List\_Visible -- (V4) [..G], LONG}

\subsubsection*{FUNCTION}
Get the current number of visible entries in the list.
You have to be prepared to get a result
of -1, which means that the list is not visible
at all (e.g. when the window is iconifed).

\subsubsection*{SEE ALSO}
MUIA\_List\_First, MUIA\_List\_Entries, MUIA\_List\_Active



